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1. INTRODUCTION 
This document describes an implementation of Stage 2 
(William M. Waite, "Implementing Software for Non-Numeric 
Applications", Prentice-Hall N.J., 1973) for PDP-11 Computer 
Systems operating under RT-11. Stage 2 is a general purpose 
macro processor designed to port software written for abstract 
Machines. The macro processor is itself protable Saing written . 


for an abstract machine called "FLUB" 


2. PROGRAMS 


The dectape contains the following modules: 


STG2.FLB - FLUB-CODE OF STAGE 2 (W.M. WAITE) 
FLUB.ST2 FLUS MACRO DEFINITIONS (P.H. HEINRICH) 
OPT.ST2 OPTIMIZATION MACRO DEFINITIONS (P.H. HEINRICH) 
ST2CMD.MAC COMMAND INPUT MODULE. (D.M. NESSETT) 
ST2RON.MAC INPUT SUBROUTINES MODULE (D.M. NESSETT) 
ST2WTN.MAC OUTPUT SUBROUTINES MODULE (D.M. NESSETT) 
ST2MSC.MAC MISC. SUBROUTINES MODULE (D.M. NESSETT) 
ST2DAT . MAC DATA SECTION MODULE (D.M. NESSETT) 
ST2DFN.MAC DEFINITIONS MODULE (D.M. NESSETT) 
BOOT.MAC STAGE 2 IN EXPANDED FORM 

BOOT.OBJ STAGE 2 OBJECT MODULE 


ST2BLD.BAT BATCH STREAM FOR BUILDING STAGE 2 (D.M. NESSETT) 


3. IMPLEMENTATIONS 

This implementation of Stage 2 was achieved by modifying 
Peter Heinrich's DOS-11 implementation so that it could 
operate under RT-11. Heinrich's abstract machine implementation 
did not require any modification to run under RT-11, but the 
supporting subroutines (to handle I/0 and command dialog) 
were completely re-written. This involved the development 
of record I/0 subroutines, since all I/0 in RT-11 is physical 
1/0. The detailed operation of these routines is discussed 


below. 


4. PREREQUISITES 
RT-11/V2. If processor is not a PDP-11/40 or 45, EAE 


must exist. 


5. RESTRICTIONS | 

Since all Input channels are treated as if they were 
concentrated into a single file, the Stage 2 command “change 
I/0 channels and Copy Text" cannot be used to change the input 


channel number. 
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6. INSTALLATION 

The installation of Stage 2/RT-11 is accomplished by 
running the batch stream "ST2BLD.BAT". This batch stream 
must first be transferred to the system device by mounting 


the distribution dectape onto DT@ and executing: 


. R PIP 
* SY:ST2BLD.BAT = DT:ST2BLD.BAT 
*<CNTL C> 


The batch monitor must then be linked into RT-11 (see RT-11 
System Reference Manual (DEC-11-ORUGA-C-D) Chapter 12) and 
the batch stream executed by typing: | 


R BATCH 
* ST2BLD 


If the RT-11 installation cannot run batch for some reason 
(e.g. the PDP-11 has less than 12K of core). The file ST2BLD.BAT 
should be listed and the commands which are contained therein 


followed manually. 


7. STAGE 2 V@3-3/RT-11 

Stage 2 uses all core available. The I/0 is double 
buffered (at the block level) and the error messages are 
those standard for Stage 2. Input to Stage 2/RT-11 may 
consist of from one to three output files and from one to 
six daput files. Input files are treated as though they, 
have been concatenated into one file in the same order as 
they appear‘on the command line. Output files are available 


on Stage 2 Channels 3, 4, and 5, 


For example: 

A. The following defines one output file (for Stage 2 
Channel 3) and three input files (which will be 
read by Stage 2 as if they had been concatenated 
together). | 


x OUTPUT.MAC = MACRO.DFN, TEXT1.ST2, TEXT2.ST2 


B. The following defines two output files (on Stage 2 
Channels 3 and 5). 


* QUTPUT.MAC,, AUX.LST = MACRO.DFN, TEXT1.ST2, TEXT2.ST2 


C. The following uses the default extension capability 
of Stage 2 (output file 1 = MAC, output file 2 =L0G, 
output file 3 = LST, all input files = ST2). 


* OUTPUT, LISTNG, ERRORS = MACRO, TEXT1, TEXT2 


This is equivalent to: 


* QUTPUT. MAC, LISTNG.LOG, ERRORS.LST = MACRO.ST2, 
TEXT1.ST2, TEXT2.ST2 


8. IMPLEMENTATION GUIDE FOR STAGE 2/RT-11 
A. INTRODUCTION 
This document contains a written description. 
of the RT-11 implementation of ‘Stage 2 (flowcharts 
are to be found in Section 9). Since the RT-11 
implementation is a madification of Peter H. Heinrich's 


DOS-11 implementation (DECUS NO. 11-158), some- 


of the information contained herein describes Heinrich's 
design of the FLUB abstract machine for the PDP-11. In 
order that credit is given gtiers credit is due, the FLUB 
implementation will be briefly discussed in Section 8B and 
the RT-11 dependant sections of Stage 2/RT-11 will be 


covered in Section C. 


B. PODP-11 FLUB IMPLEMENTATION 

The maceviat in this section briefly describes the 
FLUB. implementation designed by Peter H. Heinrich for PDP-11 
Systems. It is assumed that the panier ac thoroughly familiar 
with the architecture of FLUB and with Stage 2's implementation 
on the FLUB abstract machine. Those unfamiliar with these 
Should read the relevant sections of William M. Waite's 
book (“Implementing Software for Non-Numeric Applications", 


Prentice-Hall, N.J., 1973.) before proceeding. 


The major design decision that must be made when 
implementing FLUB is how to represent FLUB words. Each FLUB 
word consists of three fields: | 

1) The VAL field; 
aid 2) The PTR field; 

3) The FLG field. 

Heinrich-chose to represent these fields as bytes for the 
FLAG and VAL fields and as a 16-bit word for the PTR field. 
Since operations upon FLUB words cannot be executed directly 
but must first be loaded into a FLUB "register", the 
representation of these registers also needs to be described. 


Each register field corresponds to one PDP-11 16-bit word. 


Each register field is not contiguous with the other two 
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fields of the registar, but is contained in an array of 

fields of its own type. Thus FLG.7 (the FLG field for 

register 7) is contiguous with FLG.8 not with VAL.7 (this 

is in keeping with Waite's suggested implementation technique 
for FLUB's registers). The absolute physical address where 
FLUB memory begins is kept in R3 (which is called "BASE" 

in the assembly code). R4 and R5 are used to hold respectively 
the line buffer read pointer (LBR) and the line buffer write 
pointer (LBW). 


C. RT-11 DEPENDENT SECTIONS OF STAGE 2/RT-11 

Anyone examining the macro definitions for State 2/RT-11 
will notice that there are subroutine calls imbedded into 
five of the macro bodies. These five subroutines and their 
uses are: | | 

1) IWRCH - Write a character to the line buffer; 

2) CLOSE - Close a Stage 2 input channel; 

3) READ - Read the next line buffer from the input stream; 


4) WRITE - Write the current line buffer to an output 


saa channel; 


5) ERRMSG - Output an error message. 

The first two of these are fairly simple and are functionally 
identical to the routines provided in Heinrich's DOS-11 
implementation. 1WRCH simply performs a “MOVB" to insert 

the given character into the line buffer. CLOSE does 

nothing useful, since in the RT-11 version of Stage 2 (as 

in the DOS-11 version) the capability of rewinding input 
channels is not provided (CLOSE appears only in the macro 
definition of the FLUB command "REWIND"). The routine 


ERRMSG is also fairly simple and its operation should be 


obvious from its listing. The two remaining subroutines - 
READ and WRITE - are not as simple, however, and will be 


discussed in detail. 


The read software module is composed of four sections: 
1) The grin subeoutane (READ); 
2) The next line subroutine (NXTLNE); 
| 3) The next block subroutine (NXTBLK); 
and 
4) The next file subroutine (NXTFIL). 
The main routine - READ - checks the input channel number. 
If this is zero, an automatic EOF is returned. If the channel 
number is equal to one, NXTLNE is called to get the next 
line from the current input block. If the channel number is - 
neither zero nor one, an error code of two is returned to 


the caller. 


_ONXTLNE tries to obtain a new line buffer from the 
current input block. If this is possible, NXTLNE returns 
with the C bit clear to indicate success. If this is not 
possible, NXTBLK is called to return the next block and 
initiate the transfer of the following block from the input 
device. NXTLNE determines it has a complete line when it 
transfers a carriage return (line feeds are ignored - not 
transferred to line buffer - by NXTLNE). The operation of 
NXTLNE is dependent on a number of pointers into various 
character arrays: 

(4) ILNEPT - This pointer keeps track of the 
position in the line buffer where the next 
character from the current block is to be 


inserted. 


(ii) IBLKPT - This pointer is used to keep track 
of where in the current block the next line 


begins. 


(iii) ICBKEN - This location contains the address 


of the end of the current block. 


(iv) IENDBF - The address of the end of the line 
buffer. 


As was said previously, NXTBLK returns the next block 
in the input stream. Ideally this block has already been 
transferred from the current input device. If that transfer 
has not yet finished, NXTBLK waits for its completion. 
When the block becomes available, two pointers (FILBUF and 
ICRBUF) are exchanged to indicate which buffer is being used 
and which is being filled. IBLKPT is then loaded to contain 
the first character address of the current block and ICBKEN 
is updated. After these operations have been accomplished, 
NXTBLK attempts to read the next block from the input file. 
If there are no more blocks in this file, NXTFIL is called 
in an attempt to locate another input channel. Otherwise, 
NXTBLK returns to its caller with the C bit set to indicate 


success. 


The first time it is called, NXTFIL sequences through 
the input channel numbers 3-8 in an attempt to find a file 
which was Saanee by command dialog (see below). If this 
search is successful, NXTFIL updates the variable "INPCHN" 
Te) that it contains the current input channel number. Each 


subsequent call to NXTFIL begins searching from this number 
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for another defined input channel. If this search is 
successful, “INPCHN" is updated and the routine returns 
to its caller. If the search is unsuccessful, bit 9 in 


"FLBFLG" is set and NXTFIL returns control to its caller. 


The write module is composed of three routines: 


1) The main subroutine (WRITE); 


2) The next rine subroutine (NXTLNE) 3; 
and | 
3) The next black subroutine (NXTBLK). 


"WRITE" first tests the Stage 2 channel number to see if 

it is zero. If so, the routine returns immediately to 

its caller after indicating a successful write. If the 
Stage | 2 channel number is non-zero, it is decremented 

by 3 to transform the Stage. 2 channel numbers 3, 4, and 5 
into their corresponding RT-11 numbers 0, 1, and 2. If 

the cranetovucd channel number is equal to neither 0, 1, 
nor 2, “WRITE” returns to its caller with an error condition 
code. If the channel number is in the proper range, the 
minus one used by FLUB to indicate end-of-line is replaced 
by a carriage return/line feed and the subroutine NXTLNE is 


called. 


NXTLNE first transforms the output channel number into 
an index by shifting it one left. This index is used when 
accessing the output pointers OLNEPT, OBLKPT and OLBKEN. 
This is necessary since simultaneous output to different 
channels is allowed in Stage 2. NXTLNE begins moving 
characters into the output block currently being constructed 


for the specified channel. If the line fits into this block, 


NXTLNE returns indicating success. If the line does not 
fit into the current block, NXTLNE places as much of the 
line as will fit into the current block and then calls 
NXTBLK. After NXTBLK returns, OBLKPT points to the first 
character position in the next block to be constructed. 
NXTLNE places the remainder of the line to be written into 


this new block and returns to its caller. 


NXTBLK tests to see if the last block write operation 
has completed. If it hasn't, NXTBLK waits for this to 
happen. It then rotates the two block buffers (by exchanging 
the pointers DRNBUF and OCRBUF) and updates pointers 
OBLKPT (which keeps track of where the next character is 
to be written into the current block) and OCBKEN (which 
holds the address of ene current block's end). A .WRITE 
is then initiated on the bigek passed to NXTBLK by NXTLNE 
and after updating the block number for the channel, control 


passes back to NXTLNE. 


D. INITIATING A STAGE 2 RUN - COMMAND DIALOG 

| Since Stage 2 runs under RT-11, some means must 
exist for executing the routine and for setting up the 
files which Stage 2 will manipulate. Initiating Stage 2 


execution is accomplished simply by the RT-11 command: 
-R STAGE2 


Input and output files are specified by an RT-11 command 
string. Interpretation of this string and 1/0 setup and 
shut-down is the responsibility of the command DIALOG 


module. 
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The command dialog module is composed of three routines: 
1) The command dialog input routine - ST2CMD; 
2) The prime input channel subroutine - PRMCHN; 
and | | 
3) The drain output channels subroutine - DRNCHN. 
ST2CMD begins by reserving all available memory for Stage 2 
by executing a .SETTOP. It saves the stack position, outputs 
the Stage. 2 title, calls the subroutine INIT to initialize | 
some pointers, ia then calls .CSIGEN.to input and interpret 
a command string from the console. After the command string 
has been processed (see description of .CSIGEN in RT-11 
System Reference Manual), the stack is restored, FLUB's 
pointers ane initialized, and the routine PRMCHN is called. 
After control returns to ST2CMD, the Stage 2 macro processor 
is called to process the files specified in the command 
input string. When this is complete, ST2CMD calls DRNCHN 


and then loops to accept a new command string. 


The Poueiues PRMCHN and DRNCHN are used basically for 
1/0 startup and shutdown. PRMCHN calls FSTFIL (which is 
an equivalent entry point of NXTFIL) to set up the first 
input file, twice calls RDBLK (which is an equivalent 
entry point of READ NXTBLK) to set up the first two read. 
block buffers, and returns. DRNCHN writes out the last 


blocks of the three output channels. 


9. FLOW CHARTS 


A. ERRMSG 


GET MSG PUT ERROR 


| ENTRY MSG INTO 
(ENTRY) BUFFER ADDRESS BUFFER 





INSERT A 


CR-LF ~ 


YES 


USE .TTYOUT GET AN 
TO PRINT EVEN ADDRESS RETURN © 


MSG TO RETURN TO 





B. IWRCH 





RETURN CODE 
= EOF 





L2 


o 


¢;. (i) READ 


- RETURN CODE 
= ERROR 
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RETURN CODE 
SET TO INDICATE 
ERROR TYPE 








(ii) NXTLNE 










SET PARTIAL 
LINE FLAG 


SET RO TO LINE 
BUFFER POINTER & 
R1 TO BLOCK 


BUFFER POINTER 


YES 





5T 






CLEAR PARTIAL 
LINE FLAG 







RETURN CODE 
= ERROR 





(iii) NXTBLK (RDBLK) 


YES 


ENTRY 


RETURN 





NO 


Rl = INPUT -WAIT EXCHANGE 
ON BLOCK BUFFER 
CHANNEL POINTERS 



















RESET BLKPTR 
AND CURRENT 
BUFFER END 


START XFER 
OF NEXT 
BLOCK 








YES 





BUMP 
BLOCK 
NUMBER 


RETURN CODE 
= ERROR 


NXTFIL 


YES 
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(iv) NXTFIL (FSTFIL) 


we comme | neanerr 2 
| CHANNEL NO. 


YES 





NO INDICATE 
EOD 
IS 
CHANNEL 
DEF INED 
9 5 
RETURN 
RETURN Bs 
YES 
RESET 
BLOCK 
NUMBER 
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D. (i) WRITE 









STAGE 2 EOL 
(-1) BY CRLF 





eT 





SAVE OUTPUT MAKE CHANNEL 
NO. INTO AN 
co See: INDEX 


DO 
WE HAVE 
A PARTIAL 

















YES 





RO = LINE tock TOnTnE 
END OF BLOCK 
BUFFER PTR FOR THIS OUTPUT 


CHANNEL 





(iii) NXTBLK_(WRTBLK) 


RETURN CODE 


"ENTRY .WAIT ON | __YES : 
CHANNEL oo ee 


ROTATE BUFFER 
POINTERS 
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B. (i) ST2CMD 


CAPTURE 

ALL SAVE STACK OUTPUT 

wags Oy ror >) 
CORE 


CALL 
.CSIGEN 
SET UP 

LINE BUFFER 
Bs PRMCHN a 


(ii) INIT 









SETUP INITIAL 
VALUES FOR 
POINTERS AND 
INDICES 
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(iii) PRMCHN 
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10. BATCH STREAM LISTINGS 


SIOS/ NTI : 


es eecee 


eee e eee 


: 


SHESSAGCE/ WAIT PLEASS NOVNT DISTRIBUTION DECTAPE ON UIT 9 
“R PIP 
TOY? . R/7 KE DT: STST.St2, STE2.FLB, FLUB.ST2, 0PT.ST2/X 
SOY? 2. R/S? &. BATS . 
x 23% ° eo &/ EDT: ST2DFN. TAC 
SHESSAGE/IOWAIT If YOU WISH TO ASSEMBLE TEE RT-11 DEPENDANT 
STESSAGE/NOWAIT MODULES AND LIST THEM BITORE LINGING STAG=S2, 
SlPSSASE/NOVALIT TYPE: 
SMSSSACE/NOVAIT BLDLST.BaTt 
SHESSAGE/NOVAIT 


SHESSAGE/NOWAIT IF YOU WISH TO ASSEMBLE THE RT-11 DEPENDANT 

SUESSAGL/ NOWAIT NODULES WITHOUT LISTINGS BEFS ORE LINKING STAGE 
SHISSACE/NOWAIT TYPE: 

SPESSACGE-MNOVAIT BLDASM. BaT 

GMESSAGT/NOWAIT < 


SHISSAGS/TNOWAIT IF YOU SIMPLY Wish TO LIIX ses STAGE2 OBJECT 
SIESSAGL/NGNAIT MODULES WdaICI SAVE BEEN PRAVIDED 
SEESSACE/NOWAIT TYPE: 

IES 


SAQB/iTDWALT BLDLNK. BaT 
BATCH 


tm: 
x MJ 
PY 


$2 
ig% 


O & » . ia 


£ 
’ 

_ 
ke 


22.3 


SJOB/RT11 . . , mS a cE 
! aia 
ae | 
'BLDLST. BAT! 
? i 


rrerrrrrrrrt 
g 
em PIP 
RSY22 R/HEDT: ®. MACS 
VASSIGN ° "PLEASE TYPE LIST DEVICE NAME"*’CTY’LST 
-R MACRO 
xST2CND, LST: /C=STIDIN, STLCMD 
*STSRON, LST: /C2ST2IDIN, STARDN 
#ST2NTN, LST: /C2ST2DFN, ST2NTN 
*ST2MSC, LST: /C23T2DFN, ST2MSC 
2ST2DAT, LST: /C2S9T2DFN, ST2DAT . ius 
_ XBOOT, LST: /C=ST2DFN, BOOT ; ee 
oR LINK 
SSTAGES, »LST:=STICMD, ST2RDN, STSVIN,STOMSC, ST2DAT, BOOT 
SCUAIN TEST. BAT 
shod 
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SSCB/RTLL 
t 
SORE ESECESE: 
1 ' 
IDLDASI. BAT? 
: ! 
QifTrrieiirt 
1 

.R PIP 


RSY2S.8/NE DT? &. MACS 

° a MACRO 

*xST2CUD=STIDFN, STSCTD : 
SSTARDN=ST2OPN , STZRDN 
*ST2YTNSST20FN, STAIN . 
2STIMSLCeSTLOPFN, STSNSC 
“STQVAT=STAOFN, STLDAT 


SBOOTSSTEDEN, BOOT 
.’FP’ 
SCUAIN LINKUM. BAT 
SEOJ 
SJOB/RT11 
t 
ES EREEEEES) 
1 a. 
!DLDLNX. BAT? 
! sy 
rrrrrirrrer 
.R PIP 
NOY: ®.2/KEDT? 2. OS ISK 
SCHAIN LINKXUM. BAT - 
SEOS | : 
S.JIGE/RTIi 
t 
TI? yr rT TT TT2 
t ? 
ILINKUM. BAT! 
: r 
rTy2rer27T7s 
! 
.R LINX . 
*STAGER*STREND, ST2RDN, STAWTN, STEMSC, ST2DAT, BCOT 
SCHAIN TEST. BAT ; 
SEOJ 
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SJOB/RT 11 
| MTTTTTTIITT 
TEST. BAT : 
tresnereeye7 


SMESSAGE/NOWAIT THE STAGE2 TEST WILL BE RUN TWICE, ONCE 
SMESSAGE/TNOWAIT FOR THE STAGE2 PROVIDED AND ONCE FOR THE 
SMESSAGE/NOWAIT STAGE2 CONSTRUCTED IN THE TEST 

.R STAGE2 

“TEMP, TT: =FLUB.ST2,STG2.FLB 

*STG2, TT: =OPT. ST2, TEMP. MAC 

.R MACRO | 

*STG229T2DFN, STG2 

.R LINK 

x TEST=ST2CMD, ST2RDN, ST2WTN, ST2MSC ,ST2DAT, STG2 

.R TEST 

xO0UT1, ERR1SST2T 

-R STAGE2 

*0UT2, ERR2*ST2T 


*LST: >ERRI.LOG 

*LST: =OUT2. MAC 

*LST: 2ERR2. LOG 

*SY: ST2CMD. x, STAZRON. &, STAWIN. *&, ST2MSC. *%, ST2DAT. #/“D 
*xSY:ST2DFN.*, BOOT. *%, TEMP. *,STG2.2/D 

*SY¥: OPT. ST2, FLUB.ST2,ST2T.ST2/D 

*SY:*%.BAT, *. CTL, TEST. SAV/D 

xOUT1. MAC, ERR1. LOG, OUT2. MAC, ERR2. LOG/D 

SY: 7/8 

SEOJ 
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